<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.9.2"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>GrPPI: gMock Cheat Sheet</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="logo.svg"/></td>
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">GrPPI
   &#160;<span id="projectnumber">1.0</span>
   </div>
   <div id="projectbrief">Generic and Reusable Parallel Pattern Interface</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.2 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search','.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

</div><!-- top -->
<div class="PageDoc"><div class="header">
  <div class="headertitle">
<div class="title">gMock Cheat Sheet </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="autotoc_md111"></a>
Defining a Mock Class</h1>
<h2><a class="anchor" id="MockClass"></a>
Mocking a Normal Class</h2>
<p>Given</p>
<div class="fragment"><div class="line"><span class="keyword">class </span>Foo {</div>
<div class="line">  ...</div>
<div class="line">  <span class="keyword">virtual</span> ~Foo();</div>
<div class="line">  <span class="keyword">virtual</span> <span class="keywordtype">int</span> GetSize() <span class="keyword">const</span> = 0;</div>
<div class="line">  <span class="keyword">virtual</span> <span class="keywordtype">string</span> Describe(<span class="keyword">const</span> <span class="keywordtype">char</span>* name) = 0;</div>
<div class="line">  <span class="keyword">virtual</span> <span class="keywordtype">string</span> Describe(<span class="keywordtype">int</span> type) = 0;</div>
<div class="line">  <span class="keyword">virtual</span> <span class="keywordtype">bool</span> Process(Bar elem, <span class="keywordtype">int</span> count) = 0;</div>
<div class="line">};</div>
</div><!-- fragment --><p>(note that <code>~Foo()</code> <b>must</b> be virtual) we can define its mock as</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include &quot;gmock/gmock.h&quot;</span></div>
<div class="line"> </div>
<div class="line"><span class="keyword">class </span>MockFoo : <span class="keyword">public</span> Foo {</div>
<div class="line">  ...</div>
<div class="line">  <a class="code" href="cmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-function-mocker_8h.html#a05ffc29d0784b131ee178da190d31397">MOCK_METHOD</a>(<span class="keywordtype">int</span>, GetSize, (), (<span class="keyword">const</span>, <span class="keyword">override</span>));</div>
<div class="line">  <a class="code" href="cmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-function-mocker_8h.html#a05ffc29d0784b131ee178da190d31397">MOCK_METHOD</a>(<span class="keywordtype">string</span>, Describe, (<span class="keyword">const</span> <span class="keywordtype">char</span>* name), (<span class="keyword">override</span>));</div>
<div class="line">  <a class="code" href="cmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-function-mocker_8h.html#a05ffc29d0784b131ee178da190d31397">MOCK_METHOD</a>(<span class="keywordtype">string</span>, Describe, (<span class="keywordtype">int</span> type), (<span class="keyword">override</span>));</div>
<div class="line">  <a class="code" href="cmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-function-mocker_8h.html#a05ffc29d0784b131ee178da190d31397">MOCK_METHOD</a>(<span class="keywordtype">bool</span>, Process, (Bar elem, <span class="keywordtype">int</span> count), (<span class="keyword">override</span>));</div>
<div class="line">};</div>
<div class="ttc" id="acmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-function-mocker_8h_html_a05ffc29d0784b131ee178da190d31397"><div class="ttname"><a href="cmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-function-mocker_8h.html#a05ffc29d0784b131ee178da190d31397">MOCK_METHOD</a></div><div class="ttdeci">#define MOCK_METHOD(...)</div><div class="ttdef"><b>Definition:</b> cmake-build-debug/googletest-src/googlemock/include/gmock/gmock-function-mocker.h:77</div></div>
</div><!-- fragment --><p>To create a "nice" mock, which ignores all uninteresting calls, a "naggy" mock, which warns on all uninteresting calls, or a "strict" mock, which treats them as failures:</p>
<div class="fragment"><div class="line">using ::testing::NiceMock;</div>
<div class="line">using ::testing::NaggyMock;</div>
<div class="line">using ::testing::StrictMock;</div>
<div class="line"> </div>
<div class="line">NiceMock&lt;MockFoo&gt; nice_foo;      <span class="comment">// The type is a subclass of MockFoo.</span></div>
<div class="line">NaggyMock&lt;MockFoo&gt; naggy_foo;    <span class="comment">// The type is a subclass of MockFoo.</span></div>
<div class="line">StrictMock&lt;MockFoo&gt; strict_foo;  <span class="comment">// The type is a subclass of MockFoo.</span></div>
</div><!-- fragment --><p>{: .callout .note} <b>Note:</b> A mock object is currently naggy by default. We may make it nice by default in the future.</p>
<h2><a class="anchor" id="MockTemplate"></a>
Mocking a Class Template</h2>
<p>Class templates can be mocked just like any class.</p>
<p>To mock</p>
<div class="fragment"><div class="line"><span class="keyword">template</span> &lt;<span class="keyword">typename</span> Elem&gt;</div>
<div class="line"><span class="keyword">class </span>StackInterface {</div>
<div class="line">  ...</div>
<div class="line">  <span class="keyword">virtual</span> ~StackInterface();</div>
<div class="line">  <span class="keyword">virtual</span> <span class="keywordtype">int</span> GetSize() <span class="keyword">const</span> = 0;</div>
<div class="line">  <span class="keyword">virtual</span> <span class="keywordtype">void</span> Push(<span class="keyword">const</span> Elem&amp; x) = 0;</div>
<div class="line">};</div>
</div><!-- fragment --><p>(note that all member functions that are mocked, including <code>~StackInterface()</code> <b>must</b> be virtual).</p>
<div class="fragment"><div class="line"><span class="keyword">template</span> &lt;<span class="keyword">typename</span> Elem&gt;</div>
<div class="line"><span class="keyword">class </span>MockStack : <span class="keyword">public</span> StackInterface&lt;Elem&gt; {</div>
<div class="line">  ...</div>
<div class="line">  <a class="code" href="cmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-function-mocker_8h.html#a05ffc29d0784b131ee178da190d31397">MOCK_METHOD</a>(<span class="keywordtype">int</span>, GetSize, (), (<span class="keyword">const</span>, <span class="keyword">override</span>));</div>
<div class="line">  <a class="code" href="cmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-function-mocker_8h.html#a05ffc29d0784b131ee178da190d31397">MOCK_METHOD</a>(<span class="keywordtype">void</span>, Push, (<span class="keyword">const</span> Elem&amp; x), (<span class="keyword">override</span>));</div>
<div class="line">};</div>
</div><!-- fragment --><h2><a class="anchor" id="autotoc_md112"></a>
Specifying Calling Conventions for Mock Functions</h2>
<p>If your mock function doesn't use the default calling convention, you can specify it by adding <code>Calltype(convention)</code> to <code>MOCK_METHOD</code>'s 4th parameter. For example,</p>
<div class="fragment"><div class="line"><a class="code" href="cmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-function-mocker_8h.html#a05ffc29d0784b131ee178da190d31397">MOCK_METHOD</a>(<span class="keywordtype">bool</span>, Foo, (<span class="keywordtype">int</span> n), (Calltype(STDMETHODCALLTYPE)));</div>
<div class="line"><a class="code" href="cmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-function-mocker_8h.html#a05ffc29d0784b131ee178da190d31397">MOCK_METHOD</a>(<span class="keywordtype">int</span>, Bar, (<span class="keywordtype">double</span> x, <span class="keywordtype">double</span> y),</div>
<div class="line">            (<span class="keyword">const</span>, Calltype(STDMETHODCALLTYPE)));</div>
</div><!-- fragment --><p>where <code>STDMETHODCALLTYPE</code> is defined by <code>&lt;objbase.h&gt;</code> on Windows.</p>
<h1><a class="anchor" id="UsingMocks"></a>
Using Mocks in Tests</h1>
<p>The typical work flow is:</p>
<ol type="1">
<li>Import the gMock names you need to use. All gMock symbols are in the <code>testing</code> namespace unless they are macros or otherwise noted.</li>
<li>Create the mock objects.</li>
<li>Optionally, set the default actions of the mock objects.</li>
<li>Set your expectations on the mock objects (How will they be called? What will they do?).</li>
<li>Exercise code that uses the mock objects; if necessary, check the result using googletest assertions.</li>
<li>When a mock object is destructed, gMock automatically verifies that all expectations on it have been satisfied.</li>
</ol>
<p>Here's an example:</p>
<div class="fragment"><div class="line"><a class="code" href="namespacetesting.html#adae3994eb444d1ad2dd602454b854663">using ::testing::Return</a>;                          <span class="comment">// #1</span></div>
<div class="line"> </div>
<div class="line"><a class="code" href="cmake-build-debug_2googletest-src_2googletest_2include_2gtest_2gtest_8h.html#ab5540a6d621853916be8240ff51819cf">TEST</a>(BarTest, DoesThis) {</div>
<div class="line">  MockFoo foo;                                    <span class="comment">// #2</span></div>
<div class="line"> </div>
<div class="line">  <a class="code" href="cmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-spec-builders_8h.html#a5b12ae6cf84f0a544ca811b380c37334">ON_CALL</a>(foo, GetSize())                         <span class="comment">// #3</span></div>
<div class="line">      .WillByDefault(<a class="code" href="namespacetesting.html#adae3994eb444d1ad2dd602454b854663">Return</a>(1));</div>
<div class="line">  <span class="comment">// ... other default actions ...</span></div>
<div class="line"> </div>
<div class="line">  <a class="code" href="cmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-spec-builders_8h.html#a535a6156de72c1a2e25a127e38ee5232">EXPECT_CALL</a>(foo, Describe(5))                   <span class="comment">// #4</span></div>
<div class="line">      .Times(3)</div>
<div class="line">      .WillRepeatedly(<a class="code" href="namespacetesting.html#adae3994eb444d1ad2dd602454b854663">Return</a>(<span class="stringliteral">&quot;Category 5&quot;</span>));</div>
<div class="line">  <span class="comment">// ... other expectations ...</span></div>
<div class="line"> </div>
<div class="line">  <a class="code" href="cmake-build-debug_2googletest-src_2googletest_2include_2gtest_2gtest_8h.html#a4159019abda84f5366acdb7604ff220a">EXPECT_EQ</a>(<span class="stringliteral">&quot;good&quot;</span>, MyProductionFunction(&amp;foo));  <span class="comment">// #5</span></div>
<div class="line">}                                                 <span class="comment">// #6</span></div>
<div class="ttc" id="acmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-spec-builders_8h_html_a535a6156de72c1a2e25a127e38ee5232"><div class="ttname"><a href="cmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-spec-builders_8h.html#a535a6156de72c1a2e25a127e38ee5232">EXPECT_CALL</a></div><div class="ttdeci">#define EXPECT_CALL(obj, call)</div></div>
<div class="ttc" id="acmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-spec-builders_8h_html_a5b12ae6cf84f0a544ca811b380c37334"><div class="ttname"><a href="cmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-spec-builders_8h.html#a5b12ae6cf84f0a544ca811b380c37334">ON_CALL</a></div><div class="ttdeci">#define ON_CALL(obj, call)</div></div>
<div class="ttc" id="acmake-build-debug_2googletest-src_2googletest_2include_2gtest_2gtest_8h_html_a4159019abda84f5366acdb7604ff220a"><div class="ttname"><a href="cmake-build-debug_2googletest-src_2googletest_2include_2gtest_2gtest_8h.html#a4159019abda84f5366acdb7604ff220a">EXPECT_EQ</a></div><div class="ttdeci">#define EXPECT_EQ(val1, val2)</div><div class="ttdef"><b>Definition:</b> cmake-build-debug/googletest-src/googletest/include/gtest/gtest.h:2024</div></div>
<div class="ttc" id="acmake-build-debug_2googletest-src_2googletest_2include_2gtest_2gtest_8h_html_ab5540a6d621853916be8240ff51819cf"><div class="ttname"><a href="cmake-build-debug_2googletest-src_2googletest_2include_2gtest_2gtest_8h.html#ab5540a6d621853916be8240ff51819cf">TEST</a></div><div class="ttdeci">#define TEST(test_suite_name, test_name)</div><div class="ttdef"><b>Definition:</b> cmake-build-debug/googletest-src/googletest/include/gtest/gtest.h:2334</div></div>
<div class="ttc" id="anamespacetesting_html_adae3994eb444d1ad2dd602454b854663"><div class="ttname"><a href="namespacetesting.html#adae3994eb444d1ad2dd602454b854663">testing::Return</a></div><div class="ttdeci">internal::ReturnAction&lt; R &gt; Return(R value)</div><div class="ttdef"><b>Definition:</b> cmake-build-debug/googletest-src/googlemock/include/gmock/gmock-actions.h:1244</div></div>
</div><!-- fragment --><h1><a class="anchor" id="OnCall"></a>
Setting Default Actions</h1>
<p>gMock has a <b>built-in default action</b> for any function that returns <code>void</code>, <code>bool</code>, a numeric value, or a pointer. In C++11, it will additionally returns the default-constructed value, if one exists for the given type.</p>
<p>To customize the default action for functions with return type *<code>T</code>*:</p>
<div class="fragment"><div class="line">using ::testing::DefaultValue;</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Sets the default value to be returned. T must be CopyConstructible.</span></div>
<div class="line">DefaultValue&lt;T&gt;::Set(value);</div>
<div class="line"><span class="comment">// Sets a factory. Will be invoked on demand. T must be MoveConstructible.</span></div>
<div class="line"><span class="comment">//  T MakeT();</span></div>
<div class="line">DefaultValue&lt;T&gt;::SetFactory(&amp;MakeT);</div>
<div class="line"><span class="comment">// ... use the mocks ...</span></div>
<div class="line"><span class="comment">// Resets the default value.</span></div>
<div class="line">DefaultValue&lt;T&gt;::Clear();</div>
</div><!-- fragment --><p>Example usage:</p>
<div class="fragment"><div class="line"><span class="comment">// Sets the default action for return type std::unique_ptr&lt;Buzz&gt; to</span></div>
<div class="line"><span class="comment">// creating a new Buzz every time.</span></div>
<div class="line">DefaultValue&lt;std::unique_ptr&lt;Buzz&gt;&gt;::SetFactory(</div>
<div class="line">    [] { <span class="keywordflow">return</span> MakeUnique&lt;Buzz&gt;(AccessLevel::kInternal); });</div>
<div class="line"> </div>
<div class="line"><span class="comment">// When this fires, the default action of MakeBuzz() will run, which</span></div>
<div class="line"><span class="comment">// will return a new Buzz object.</span></div>
<div class="line"><a class="code" href="cmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-spec-builders_8h.html#a535a6156de72c1a2e25a127e38ee5232">EXPECT_CALL</a>(mock_buzzer_, MakeBuzz(<span class="stringliteral">&quot;hello&quot;</span>)).Times(AnyNumber());</div>
<div class="line"> </div>
<div class="line"><span class="keyword">auto</span> buzz1 = mock_buzzer_.MakeBuzz(<span class="stringliteral">&quot;hello&quot;</span>);</div>
<div class="line"><span class="keyword">auto</span> buzz2 = mock_buzzer_.MakeBuzz(<span class="stringliteral">&quot;hello&quot;</span>);</div>
<div class="line"><a class="code" href="cmake-build-debug_2googletest-src_2googletest_2include_2gtest_2gtest_8h.html#a6ae7443947f25abc58bfcfcfc56b0d75">EXPECT_NE</a>(<span class="keyword">nullptr</span>, buzz1);</div>
<div class="line"><a class="code" href="cmake-build-debug_2googletest-src_2googletest_2include_2gtest_2gtest_8h.html#a6ae7443947f25abc58bfcfcfc56b0d75">EXPECT_NE</a>(<span class="keyword">nullptr</span>, buzz2);</div>
<div class="line"><a class="code" href="cmake-build-debug_2googletest-src_2googletest_2include_2gtest_2gtest_8h.html#a6ae7443947f25abc58bfcfcfc56b0d75">EXPECT_NE</a>(buzz1, buzz2);</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Resets the default action for return type std::unique_ptr&lt;Buzz&gt;,</span></div>
<div class="line"><span class="comment">// to avoid interfere with other tests.</span></div>
<div class="line">DefaultValue&lt;std::unique_ptr&lt;Buzz&gt;&gt;::Clear();</div>
<div class="ttc" id="acmake-build-debug_2googletest-src_2googletest_2include_2gtest_2gtest_8h_html_a6ae7443947f25abc58bfcfcfc56b0d75"><div class="ttname"><a href="cmake-build-debug_2googletest-src_2googletest_2include_2gtest_2gtest_8h.html#a6ae7443947f25abc58bfcfcfc56b0d75">EXPECT_NE</a></div><div class="ttdeci">#define EXPECT_NE(val1, val2)</div><div class="ttdef"><b>Definition:</b> cmake-build-debug/googletest-src/googletest/include/gtest/gtest.h:2026</div></div>
</div><!-- fragment --><p>To customize the default action for a particular method of a specific mock object, use <code><a class="el" href="cmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-spec-builders_8h.html#a5b12ae6cf84f0a544ca811b380c37334">ON_CALL()</a></code>. <code><a class="el" href="cmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-spec-builders_8h.html#a5b12ae6cf84f0a544ca811b380c37334">ON_CALL()</a></code> has a similar syntax to <code><a class="el" href="cmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-spec-builders_8h.html#a535a6156de72c1a2e25a127e38ee5232">EXPECT_CALL()</a></code>, but it is used for setting default behaviors (when you do not require that the mock method is called). See <a href="gmock_cook_book.md#UseOnCall">here</a> for a more detailed discussion.</p>
<div class="fragment"><div class="line"><a class="code" href="cmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-spec-builders_8h.html#a5b12ae6cf84f0a544ca811b380c37334">ON_CALL</a>(mock-<span class="keywordtype">object</span>, method(matchers))</div>
<div class="line">    .With(multi-argument-matcher)   ?</div>
<div class="line">    .WillByDefault(action);</div>
</div><!-- fragment --><h1><a class="anchor" id="ExpectCall"></a>
Setting Expectations</h1>
<p><code><a class="el" href="cmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-spec-builders_8h.html#a535a6156de72c1a2e25a127e38ee5232">EXPECT_CALL()</a></code> sets <b>expectations</b> on a mock method (How will it be called? What will it do?):</p>
<div class="fragment"><div class="line"><a class="code" href="cmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-spec-builders_8h.html#a535a6156de72c1a2e25a127e38ee5232">EXPECT_CALL</a>(mock-<span class="keywordtype">object</span>, method (matchers)?)</div>
<div class="line">     .With(multi-argument-matcher)  ?</div>
<div class="line">     .Times(cardinality)            ?</div>
<div class="line">     .InSequence(sequences)         *</div>
<div class="line">     .After(expectations)           *</div>
<div class="line">     .WillOnce(action)              *</div>
<div class="line">     .WillRepeatedly(action)        ?</div>
<div class="line">     .RetiresOnSaturation();        ?</div>
</div><!-- fragment --><p>For each item above, <code>?</code> means it can be used at most once, while <code>*</code> means it can be used any number of times.</p>
<p>In order to pass, <code>EXPECT_CALL</code> must be used before the calls are actually made.</p>
<p>The <code>(matchers)</code> is a comma-separated list of matchers that correspond to each of the arguments of <code>method</code>, and sets the expectation only for calls of <code>method</code> that matches all of the matchers.</p>
<p>If <code>(matchers)</code> is omitted, the expectation is the same as if the matchers were set to anything matchers (for example, <code>(_, _, _, _)</code> for a four-arg method).</p>
<p>If <code>Times()</code> is omitted, the cardinality is assumed to be:</p>
<ul>
<li><code>Times(1)</code> when there is neither <code>WillOnce()</code> nor <code>WillRepeatedly()</code>;</li>
<li><code>Times(n)</code> when there are <code>n</code> <code>WillOnce()</code>s but no <code>WillRepeatedly()</code>, where <code>n</code> &gt;= 1; or</li>
<li><code>Times(AtLeast(n))</code> when there are <code>n</code> <code>WillOnce()</code>s and a <code>WillRepeatedly()</code>, where <code>n</code> &gt;= 0.</li>
</ul>
<p>A method with no <code><a class="el" href="cmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-spec-builders_8h.html#a535a6156de72c1a2e25a127e38ee5232">EXPECT_CALL()</a></code> is free to be invoked <em>any number of times</em>, and the default action will be taken each time.</p>
<h1><a class="anchor" id="MatcherList"></a>
Matchers</h1>
<p>A <b>matcher</b> matches a <em>single</em> argument. You can use it inside <code><a class="el" href="cmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-spec-builders_8h.html#a5b12ae6cf84f0a544ca811b380c37334">ON_CALL()</a></code> or <code><a class="el" href="cmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-spec-builders_8h.html#a535a6156de72c1a2e25a127e38ee5232">EXPECT_CALL()</a></code>, or use it to validate a value directly using two macros:</p>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft">Macro   </th><th class="markdownTableHeadLeft">Description    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code><a class="el" href="cmake-build-release_2googletest-src_2googlemock_2include_2gmock_2gmock-matchers_8h.html#ac31e206123aa702e1152bb2735b31409">EXPECT_THAT(actual_value, matcher)</a></code>   </td><td class="markdownTableBodyLeft">Asserts that <code>actual_value</code> matches <code>matcher</code>.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code><a class="el" href="cmake-build-release_2googletest-src_2googlemock_2include_2gmock_2gmock-matchers_8h.html#a41d888579850c16583baea33ee8d057e">ASSERT_THAT(actual_value, matcher)</a></code>   </td><td class="markdownTableBodyLeft">The same as <code><a class="el" href="cmake-build-release_2googletest-src_2googlemock_2include_2gmock_2gmock-matchers_8h.html#ac31e206123aa702e1152bb2735b31409">EXPECT_THAT(actual_value, matcher)</a></code>, except that it generates a <b>fatal</b> failure.   </td></tr>
</table>
<p>{: .callout .note} <b>Note:</b> Although equality matching via <code>EXPECT_THAT(actual_value, expected_value)</code> is supported, prefer to make the comparison explicit via <code><a class="el" href="cmake-build-release_2googletest-src_2googlemock_2include_2gmock_2gmock-matchers_8h.html#ac31e206123aa702e1152bb2735b31409">EXPECT_THAT(actual_value, Eq(expected_value))</a></code> or <code>EXPECT_EQ(actual_value, expected_value)</code>.</p>
<p>Built-in matchers (where <code>argument</code> is the function argument, e.g. <code>actual_value</code> in the example above, or when used in the context of <code><a class="el" href="cmake-build-release_2googletest-src_2googlemock_2include_2gmock_2gmock-spec-builders_8h.html#a535a6156de72c1a2e25a127e38ee5232">EXPECT_CALL(mock_object, method(matchers))</a></code>, the arguments of <code>method</code>) are divided into several categories:</p>
<h2><a class="anchor" id="autotoc_md113"></a>
Wildcard</h2>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft">Matcher   </th><th class="markdownTableHeadLeft">Description    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>_</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> can be any value of the correct type.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>A&lt;type&gt;()</code> or <code>An&lt;type&gt;()</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> can be any value of type <code>type</code>.   </td></tr>
</table>
<h2><a class="anchor" id="autotoc_md114"></a>
Generic Comparison</h2>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft">Matcher   </th><th class="markdownTableHeadLeft">Description    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Eq(value)</code> or <code>value</code>   </td><td class="markdownTableBodyLeft"><code>argument == value</code>    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>Ge(value)</code>   </td><td class="markdownTableBodyLeft"><code>argument &gt;= value</code>    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Gt(value)</code>   </td><td class="markdownTableBodyLeft"><code>argument &gt; value</code>    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>Le(value)</code>   </td><td class="markdownTableBodyLeft"><code>argument &lt;= value</code>    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Lt(value)</code>   </td><td class="markdownTableBodyLeft"><code>argument &lt; value</code>    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>Ne(value)</code>   </td><td class="markdownTableBodyLeft"><code>argument != value</code>    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>IsFalse()</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> evaluates to <code>false</code> in a Boolean context.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code><a class="el" href="namespacetesting_1_1internal.html#ab2709373c78eb8b1c22a6ba30cceba52">IsTrue()</a></code>   </td><td class="markdownTableBodyLeft"><code>argument</code> evaluates to <code>true</code> in a Boolean context.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>IsNull()</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is a <code>NULL</code> pointer (raw or smart).    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>NotNull()</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is a non-null pointer (raw or smart).    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Optional(m)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is <code>optional&lt;&gt;</code> that contains a value matching <code>m</code>. (For testing whether an <code>optional&lt;&gt;</code> is set, check for equality with <code>nullopt</code>. You may need to use <code>Eq(nullopt)</code> if the inner type doesn't have <code>==</code>.)    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>VariantWith&lt;T&gt;(m)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is <code>variant&lt;&gt;</code> that holds the alternative of type T with a value matching <code>m</code>.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Ref(variable)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is a reference to <code>variable</code>.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>TypedEq&lt;type&gt;(value)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> has type <code>type</code> and is equal to <code>value</code>. You may need to use this instead of <code>Eq(value)</code> when the mock function is overloaded.   </td></tr>
</table>
<p>Except <code>Ref()</code>, these matchers make a <em>copy</em> of <code>value</code> in case it's modified or destructed later. If the compiler complains that <code>value</code> doesn't have a public copy constructor, try wrap it in <code>std::ref()</code>, e.g. <code>Eq(std::ref(non_copyable_value))</code>. If you do that, make sure <code>non_copyable_value</code> is not changed afterwards, or the meaning of your matcher will be changed.</p>
<p><code>IsTrue</code> and <code>IsFalse</code> are useful when you need to use a matcher, or for types that can be explicitly converted to Boolean, but are not implicitly converted to Boolean. In other cases, you can use the basic <a href="primer.md#basic-assertions"><code>EXPECT_TRUE</code> and <code>EXPECT_FALSE</code></a> assertions.</p>
<h2><a class="anchor" id="FpMatchers"></a>
Floating-Point Matchers</h2>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft">Matcher   </th><th class="markdownTableHeadLeft">Description    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>DoubleEq(a_double)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is a <code>double</code> value approximately equal to <code>a_double</code>, treating two NaNs as unequal.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>FloatEq(a_float)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is a <code>float</code> value approximately equal to <code>a_float</code>, treating two NaNs as unequal.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>NanSensitiveDoubleEq(a_double)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is a <code>double</code> value approximately equal to <code>a_double</code>, treating two NaNs as equal.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>NanSensitiveFloatEq(a_float)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is a <code>float</code> value approximately equal to <code>a_float</code>, treating two NaNs as equal.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>IsNan()</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is any floating-point type with a NaN value.   </td></tr>
</table>
<p>The above matchers use ULP-based comparison (the same as used in googletest). They automatically pick a reasonable error bound based on the absolute value of the expected value. <code>DoubleEq()</code> and <code>FloatEq()</code> conform to the IEEE standard, which requires comparing two NaNs for equality to return false. The <code>NanSensitive*</code> version instead treats two NaNs as equal, which is often what a user wants.</p>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft">Matcher   </th><th class="markdownTableHeadLeft">Description    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>DoubleNear(a_double, max_abs_error)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is a <code>double</code> value close to <code>a_double</code> (absolute error &lt;= <code>max_abs_error</code>), treating two NaNs as unequal.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>FloatNear(a_float, max_abs_error)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is a <code>float</code> value close to <code>a_float</code> (absolute error &lt;= <code>max_abs_error</code>), treating two NaNs as unequal.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>NanSensitiveDoubleNear(a_double, max_abs_error)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is a <code>double</code> value close to <code>a_double</code> (absolute error &lt;= <code>max_abs_error</code>), treating two NaNs as equal.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>NanSensitiveFloatNear(a_float, max_abs_error)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is a <code>float</code> value close to <code>a_float</code> (absolute error &lt;= <code>max_abs_error</code>), treating two NaNs as equal.   </td></tr>
</table>
<h2><a class="anchor" id="autotoc_md115"></a>
String Matchers</h2>
<p>The <code>argument</code> can be either a C string or a C++ string object:</p>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft">Matcher   </th><th class="markdownTableHeadLeft">Description    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>ContainsRegex(string)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> matches the given regular expression.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>EndsWith(suffix)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> ends with string <code>suffix</code>.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>HasSubstr(string)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> contains <code>string</code> as a sub-string.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>IsEmpty()</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is an empty string.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>MatchesRegex(string)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> matches the given regular expression with the match starting at the first character and ending at the last character.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>StartsWith(prefix)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> starts with string <code>prefix</code>.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>StrCaseEq(string)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is equal to <code>string</code>, ignoring case.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>StrCaseNe(string)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is not equal to <code>string</code>, ignoring case.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>StrEq(string)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is equal to <code>string</code>.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>StrNe(string)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is not equal to <code>string</code>.   </td></tr>
</table>
<p><code>ContainsRegex()</code> and <code>MatchesRegex()</code> take ownership of the <code>RE</code> object. They use the regular expression syntax defined <a href="advanced.md#regular-expression-syntax">here</a>. All of these matchers, except <code>ContainsRegex()</code> and <code>MatchesRegex()</code> work for wide strings as well.</p>
<h2><a class="anchor" id="autotoc_md116"></a>
Container Matchers</h2>
<p>Most STL-style containers support <code>==</code>, so you can use <code>Eq(expected_container)</code> or simply <code>expected_container</code> to match a container exactly. If you want to write the elements in-line, match them more flexibly, or get more informative messages, you can use:</p>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft">Matcher   </th><th class="markdownTableHeadLeft">Description    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>BeginEndDistanceIs(m)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is a container whose <code>begin()</code> and <code>end()</code> iterators are separated by a number of increments matching <code>m</code>. E.g. <code>BeginEndDistanceIs(2)</code> or <code>BeginEndDistanceIs(Lt(2))</code>. For containers that define a <code>size()</code> method, <code>SizeIs(m)</code> may be more efficient.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>ContainerEq(container)</code>   </td><td class="markdownTableBodyLeft">The same as <code>Eq(container)</code> except that the failure message also includes which elements are in one container but not the other.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Contains(e)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> contains an element that matches <code>e</code>, which can be either a value or a matcher.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>Each(e)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is a container where <em>every</em> element matches <code>e</code>, which can be either a value or a matcher.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>ElementsAre(e0, e1, ..., en)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> has <code>n + 1</code> elements, where the <em>i</em>-th element matches <code>ei</code>, which can be a value or a matcher.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>ElementsAreArray({e0, e1, ..., en})</code>, <code>ElementsAreArray(a_container)</code>, <code>ElementsAreArray(begin, end)</code>, <code>ElementsAreArray(array)</code>, or <code>ElementsAreArray(array, count)</code>   </td><td class="markdownTableBodyLeft">The same as <code>ElementsAre()</code> except that the expected element values/matchers come from an initializer list, STL-style container, iterator range, or C-style array.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>IsEmpty()</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is an empty container (<code>container.empty()</code>).    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>IsSubsetOf({e0, e1, ..., en})</code>, <code>IsSubsetOf(a_container)</code>, <code>IsSubsetOf(begin, end)</code>, <code>IsSubsetOf(array)</code>, or <code>IsSubsetOf(array, count)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> matches <code>UnorderedElementsAre(x0, x1, ..., xk)</code> for some subset <code>{x0, x1, ..., xk}</code> of the expected matchers.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>IsSupersetOf({e0, e1, ..., en})</code>, <code>IsSupersetOf(a_container)</code>, <code>IsSupersetOf(begin, end)</code>, <code>IsSupersetOf(array)</code>, or <code>IsSupersetOf(array, count)</code>   </td><td class="markdownTableBodyLeft">Some subset of <code>argument</code> matches <code>UnorderedElementsAre(</code>expected matchers<code>)</code>.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>Pointwise(m, container)</code>, <code>Pointwise(m, {e0, e1, ..., en})</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> contains the same number of elements as in <code>container</code>, and for all i, (the i-th element in <code>argument</code>, the i-th element in <code>container</code>) match <code>m</code>, which is a matcher on 2-tuples. E.g. <code>Pointwise(Le(), upper_bounds)</code> verifies that each element in <code>argument</code> doesn't exceed the corresponding element in <code>upper_bounds</code>. See more detail below.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>SizeIs(m)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is a container whose size matches <code>m</code>. E.g. <code>SizeIs(2)</code> or <code>SizeIs(Lt(2))</code>.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>UnorderedElementsAre(e0, e1, ..., en)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> has <code>n + 1</code> elements, and under <em>some</em> permutation of the elements, each element matches an <code>ei</code> (for a different <code>i</code>), which can be a value or a matcher.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>UnorderedElementsAreArray({e0, e1, ..., en})</code>, <code>UnorderedElementsAreArray(a_container)</code>, <code>UnorderedElementsAreArray(begin, end)</code>, <code>UnorderedElementsAreArray(array)</code>, or <code>UnorderedElementsAreArray(array, count)</code>   </td><td class="markdownTableBodyLeft">The same as <code>UnorderedElementsAre()</code> except that the expected element values/matchers come from an initializer list, STL-style container, iterator range, or C-style array.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>UnorderedPointwise(m, container)</code>, <code>UnorderedPointwise(m, {e0, e1, ..., en})</code>   </td><td class="markdownTableBodyLeft">Like <code>Pointwise(m, container)</code>, but ignores the order of elements.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>WhenSorted(m)</code>   </td><td class="markdownTableBodyLeft">When <code>argument</code> is sorted using the <code>&lt;</code> operator, it matches container matcher <code>m</code>. E.g. <code>WhenSorted(ElementsAre(1, 2, 3))</code> verifies that <code>argument</code> contains elements 1, 2, and 3, ignoring order.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>WhenSortedBy(comparator, m)</code>   </td><td class="markdownTableBodyLeft">The same as <code>WhenSorted(m)</code>, except that the given comparator instead of <code>&lt;</code> is used to sort <code>argument</code>. E.g. <code>WhenSortedBy(std::greater(), ElementsAre(3, 2, 1))</code>.   </td></tr>
</table>
<p><b>Notes:</b></p>
<ul>
<li>These matchers can also match:<ol type="1">
<li>a native array passed by reference (e.g. in <code>Foo(const int (&amp;a)[5])</code>), and</li>
<li>an array passed as a pointer and a count (e.g. in <code>Bar(const T* buffer, int len)</code> &ndash; see <a href="#MultiArgMatchers">Multi-argument Matchers</a>).</li>
</ol>
</li>
<li>The array being matched may be multi-dimensional (i.e. its elements can be arrays).</li>
<li><p class="startli"><code>m</code> in <code>Pointwise(m, ...)</code> should be a matcher for <code>::std::tuple&lt;T, U&gt;</code> where <code>T</code> and <code>U</code> are the element type of the actual container and the expected container, respectively. For example, to compare two <code>Foo</code> containers where <code>Foo</code> doesn't support <code>operator==</code>, one might write:</p>
<p class="startli">```cpp using ::std::get; MATCHER(FooEq, "") { return std::get&lt;0&gt;(arg).Equals(std::get&lt;1&gt;(arg)); } ... EXPECT_THAT(actual_foos, Pointwise(FooEq(), expected_foos)); ```</p>
</li>
</ul>
<h2><a class="anchor" id="autotoc_md117"></a>
Member Matchers</h2>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft">Matcher   </th><th class="markdownTableHeadLeft">Description    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Field(&amp;class::field, m)</code>   </td><td class="markdownTableBodyLeft"><code>argument.field</code> (or <code>argument-&gt;field</code> when <code>argument</code> is a plain pointer) matches matcher <code>m</code>, where <code>argument</code> is an object of type <em>class</em>.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>Field(field_name, &amp;class::field, m)</code>   </td><td class="markdownTableBodyLeft">The same as the two-parameter version, but provides a better error message.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Key(e)</code>   </td><td class="markdownTableBodyLeft"><code>argument.first</code> matches <code>e</code>, which can be either a value or a matcher. E.g. <code>Contains(Key(Le(5)))</code> can verify that a <code>map</code> contains a key <code>&lt;= 5</code>.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>Pair(m1, m2)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is an <code>std::pair</code> whose <code>first</code> field matches <code>m1</code> and <code>second</code> field matches <code>m2</code>.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>FieldsAre(m...)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> is a compatible object where each field matches piecewise with <code>m...</code>. A compatible object is any that supports the <code>std::tuple_size&lt;Obj&gt;</code>+<code>get&lt;I&gt;(obj)</code> protocol. In C++17 and up this also supports types compatible with structured bindings, like aggregates.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>Property(&amp;class::property, m)</code>   </td><td class="markdownTableBodyLeft"><code>argument.property()</code> (or <code>argument-&gt;property()</code> when <code>argument</code> is a plain pointer) matches matcher <code>m</code>, where <code>argument</code> is an object of type <em>class</em>. The method <code>property()</code> must take no argument and be declared as <code>const</code>.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Property(property_name, &amp;class::property, m)</code>   </td><td class="markdownTableBodyLeft">The same as the two-parameter version, but provides a better error message.   </td></tr>
</table>
<p><b>Notes:</b></p>
<ul>
<li>Don't use <code>Property()</code> against member functions that you do not own, because taking addresses of functions is fragile and generally not part of the contract of the function.</li>
</ul>
<h2><a class="anchor" id="autotoc_md118"></a>
Matching the Result of a Function, Functor, or Callback</h2>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft">Matcher   </th><th class="markdownTableHeadLeft">Description    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>ResultOf(f, m)</code>   </td><td class="markdownTableBodyLeft"><code>f(argument)</code> matches matcher <code>m</code>, where <code>f</code> is a function or functor.   </td></tr>
</table>
<h2><a class="anchor" id="autotoc_md119"></a>
Pointer Matchers</h2>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft">Matcher   </th><th class="markdownTableHeadLeft">Description    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Address(m)</code>   </td><td class="markdownTableBodyLeft">the result of <code>std::addressof(argument)</code> matches <code>m</code>.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>Pointee(m)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> (either a smart pointer or a raw pointer) points to a value that matches matcher <code>m</code>.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Pointer(m)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> (either a smart pointer or a raw pointer) contains a pointer that matches <code>m</code>. <code>m</code> will match against the raw pointer regardless of the type of <code>argument</code>.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>WhenDynamicCastTo&lt;T&gt;(m)</code>   </td><td class="markdownTableBodyLeft">when <code>argument</code> is passed through <code>dynamic_cast&lt;T&gt;()</code>, it matches matcher <code>m</code>.   </td></tr>
</table>
<h2><a class="anchor" id="MultiArgMatchers"></a>
Multi-argument Matchers</h2>
<p>Technically, all matchers match a <em>single</em> value. A "multi-argument" matcher is just one that matches a <em>tuple</em>. The following matchers can be used to match a tuple <code>(x, y)</code>:</p>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft">Matcher   </th><th class="markdownTableHeadLeft">Description    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Eq()</code>   </td><td class="markdownTableBodyLeft"><code>x == y</code>    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>Ge()</code>   </td><td class="markdownTableBodyLeft"><code>x &gt;= y</code>    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Gt()</code>   </td><td class="markdownTableBodyLeft"><code>x &gt; y</code>    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>Le()</code>   </td><td class="markdownTableBodyLeft"><code>x &lt;= y</code>    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Lt()</code>   </td><td class="markdownTableBodyLeft"><code>x &lt; y</code>    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>Ne()</code>   </td><td class="markdownTableBodyLeft"><code>x != y</code>   </td></tr>
</table>
<p>You can use the following selectors to pick a subset of the arguments (or reorder them) to participate in the matching:</p>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft">Matcher   </th><th class="markdownTableHeadLeft">Description    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>AllArgs(m)</code>   </td><td class="markdownTableBodyLeft">Equivalent to <code>m</code>. Useful as syntactic sugar in <code>.With(AllArgs(m))</code>.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>Args&lt;N1, N2, ..., Nk&gt;(m)</code>   </td><td class="markdownTableBodyLeft">The tuple of the <code>k</code> selected (using 0-based indices) arguments matches <code>m</code>, e.g. <code>Args&lt;1, 2&gt;(Eq())</code>.   </td></tr>
</table>
<h2><a class="anchor" id="autotoc_md120"></a>
Composite Matchers</h2>
<p>You can make a matcher from one or more other matchers:</p>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft">Matcher   </th><th class="markdownTableHeadLeft">Description    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>AllOf(m1, m2, ..., mn)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> matches all of the matchers <code>m1</code> to <code>mn</code>.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>AllOfArray({m0, m1, ..., mn})</code>, <code>AllOfArray(a_container)</code>, <code>AllOfArray(begin, end)</code>, <code>AllOfArray(array)</code>, or <code>AllOfArray(array, count)</code>   </td><td class="markdownTableBodyLeft">The same as <code>AllOf()</code> except that the matchers come from an initializer list, STL-style container, iterator range, or C-style array.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>AnyOf(m1, m2, ..., mn)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> matches at least one of the matchers <code>m1</code> to <code>mn</code>.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>AnyOfArray({m0, m1, ..., mn})</code>, <code>AnyOfArray(a_container)</code>, <code>AnyOfArray(begin, end)</code>, <code>AnyOfArray(array)</code>, or <code>AnyOfArray(array, count)</code>   </td><td class="markdownTableBodyLeft">The same as <code>AnyOf()</code> except that the matchers come from an initializer list, STL-style container, iterator range, or C-style array.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Not(m)</code>   </td><td class="markdownTableBodyLeft"><code>argument</code> doesn't match matcher <code>m</code>.   </td></tr>
</table>
<h2><a class="anchor" id="autotoc_md121"></a>
Adapters for Matchers</h2>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft">Matcher   </th><th class="markdownTableHeadLeft">Description    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>MatcherCast&lt;T&gt;(m)</code>   </td><td class="markdownTableBodyLeft">casts matcher <code>m</code> to type <code>Matcher&lt;T&gt;</code>.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>SafeMatcherCast&lt;T&gt;(m)</code>   </td><td class="markdownTableBodyLeft"><a href="gmock_cook_book.md#casting-matchers">safely casts</a> matcher <code>m</code> to type <code>Matcher&lt;T&gt;</code>.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Truly(predicate)</code>   </td><td class="markdownTableBodyLeft"><code>predicate(argument)</code> returns something considered by C++ to be true, where <code>predicate</code> is a function or functor.   </td></tr>
</table>
<p><code>AddressSatisfies(callback)</code> and <code>Truly(callback)</code> take ownership of <code>callback</code>, which must be a permanent callback.</p>
<h2><a class="anchor" id="MatchersAsPredicatesCheat"></a>
Using Matchers as Predicates</h2>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft">Matcher   </th><th class="markdownTableHeadLeft">Description    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Matches(m)(value)</code>   </td><td class="markdownTableBodyLeft">evaluates to <code>true</code> if <code>value</code> matches <code>m</code>. You can use <code>Matches(m)</code> alone as a unary functor.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>ExplainMatchResult(m, value, result_listener)</code>   </td><td class="markdownTableBodyLeft">evaluates to <code>true</code> if <code>value</code> matches <code>m</code>, explaining the result to <code>result_listener</code>.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Value(value, m)</code>   </td><td class="markdownTableBodyLeft">evaluates to <code>true</code> if <code>value</code> matches <code>m</code>.   </td></tr>
</table>
<h2><a class="anchor" id="autotoc_md122"></a>
Defining Matchers</h2>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft">Matcher   </th><th class="markdownTableHeadLeft">Description    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>MATCHER(IsEven, "") { return (arg % 2) == 0; }</code>   </td><td class="markdownTableBodyLeft">Defines a matcher <code>IsEven()</code> to match an even number.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>MATCHER_P(IsDivisibleBy, n, "") { *result_listener &lt;&lt; "where the remainder is " &lt;&lt; (arg % n); return (arg % n) == 0; }</code>   </td><td class="markdownTableBodyLeft">Defines a matcher <code>IsDivisibleBy(n)</code> to match a number divisible by <code>n</code>.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>MATCHER_P2(IsBetween, a, b, absl::StrCat(negation ? "isn't" : "is", " between ", PrintToString(a), " and ", PrintToString(b))) { return a &lt;= arg &amp;&amp; arg &lt;= b; }</code>   </td><td class="markdownTableBodyLeft">Defines a matcher <code>IsBetween(a, b)</code> to match a value in the range [<code>a</code>, <code>b</code>].   </td></tr>
</table>
<p><b>Notes:</b></p>
<ol type="1">
<li>The <code>MATCHER*</code> macros cannot be used inside a function or class.</li>
<li>The matcher body must be <em>purely functional</em> (i.e. it cannot have any side effect, and the result must not depend on anything other than the value being matched and the matcher parameters).</li>
<li>You can use <code>PrintToString(x)</code> to convert a value <code>x</code> of any type to a string.</li>
<li><p class="startli">You can use <code>ExplainMatchResult()</code> in a custom matcher to wrap another matcher, for example:</p>
<p class="startli">```cpp MATCHER_P(NestedPropertyMatches, matcher, "") { return ExplainMatchResult(matcher, arg.nested().property(), result_listener); } ```</p>
</li>
</ol>
<h1><a class="anchor" id="ActionList"></a>
Actions</h1>
<p><b>Actions</b> specify what a mock function should do when invoked.</p>
<h2><a class="anchor" id="autotoc_md123"></a>
Returning a Value</h2>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft"></th><th class="markdownTableHeadLeft"></th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code><a class="el" href="namespacetesting.html#adae3994eb444d1ad2dd602454b854663">Return()</a></code>   </td><td class="markdownTableBodyLeft">Return from a <code>void</code> mock function.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>Return(value)</code>   </td><td class="markdownTableBodyLeft">Return <code>value</code>. If the type of <code>value</code> is different to the mock function's return type, <code>value</code> is converted to the latter type <em>at the time the expectation is set</em>, not when the action is executed.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>ReturnArg&lt;N&gt;()</code>   </td><td class="markdownTableBodyLeft">Return the <code>N</code>-th (0-based) argument.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>ReturnNew&lt;T&gt;(a1, ..., ak)</code>   </td><td class="markdownTableBodyLeft">Return <code>new T(a1, ..., ak)</code>; a different object is created each time.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code><a class="el" href="namespacetesting.html#af05e07c0484961f2a30ba44d1d1816fe">ReturnNull()</a></code>   </td><td class="markdownTableBodyLeft">Return a null pointer.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>ReturnPointee(ptr)</code>   </td><td class="markdownTableBodyLeft">Return the value pointed to by <code>ptr</code>.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>ReturnRef(variable)</code>   </td><td class="markdownTableBodyLeft">Return a reference to <code>variable</code>.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>ReturnRefOfCopy(value)</code>   </td><td class="markdownTableBodyLeft">Return a reference to a copy of <code>value</code>; the copy lives as long as the action.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>ReturnRoundRobin({a1, ..., ak})</code>   </td><td class="markdownTableBodyLeft">Each call will return the next <code>ai</code> in the list, starting at the beginning when the end of the list is reached.   </td></tr>
</table>
<h2><a class="anchor" id="autotoc_md124"></a>
Side Effects</h2>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft"></th><th class="markdownTableHeadLeft"></th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Assign(&amp;variable, value)</code>   </td><td class="markdownTableBodyLeft">Assign <code>value</code> to variable.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>DeleteArg&lt;N&gt;()</code>   </td><td class="markdownTableBodyLeft">Delete the <code>N</code>-th (0-based) argument, which must be a pointer.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>SaveArg&lt;N&gt;(pointer)</code>   </td><td class="markdownTableBodyLeft">Save the <code>N</code>-th (0-based) argument to <code>*pointer</code>.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>SaveArgPointee&lt;N&gt;(pointer)</code>   </td><td class="markdownTableBodyLeft">Save the value pointed to by the <code>N</code>-th (0-based) argument to <code>*pointer</code>.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>SetArgReferee&lt;N&gt;(value)</code>   </td><td class="markdownTableBodyLeft">Assign <code>value</code> to the variable referenced by the <code>N</code>-th (0-based) argument.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>SetArgPointee&lt;N&gt;(value)</code>   </td><td class="markdownTableBodyLeft">Assign <code>value</code> to the variable pointed by the <code>N</code>-th (0-based) argument.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>SetArgumentPointee&lt;N&gt;(value)</code>   </td><td class="markdownTableBodyLeft">Same as <code>SetArgPointee&lt;N&gt;(value)</code>. Deprecated. Will be removed in v1.7.0.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>SetArrayArgument&lt;N&gt;(first, last)</code>   </td><td class="markdownTableBodyLeft">Copies the elements in source range [<code>first</code>, <code>last</code>) to the array pointed to by the <code>N</code>-th (0-based) argument, which can be either a pointer or an iterator. The action does not take ownership of the elements in the source range.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>SetErrnoAndReturn(error, value)</code>   </td><td class="markdownTableBodyLeft">Set <code>errno</code> to <code>error</code> and return <code>value</code>.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>Throw(exception)</code>   </td><td class="markdownTableBodyLeft">Throws the given exception, which can be any copyable value. Available since v1.1.0.   </td></tr>
</table>
<h2><a class="anchor" id="autotoc_md125"></a>
Using a Function, Functor, or Lambda as an Action</h2>
<p>In the following, by "callable" we mean a free function, <code>std::function</code>, functor, or lambda.</p>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft"></th><th class="markdownTableHeadLeft"></th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>f</code>   </td><td class="markdownTableBodyLeft">Invoke f with the arguments passed to the mock function, where f is a callable.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>Invoke(f)</code>   </td><td class="markdownTableBodyLeft">Invoke <code>f</code> with the arguments passed to the mock function, where <code>f</code> can be a global/static function or a functor.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Invoke(object_pointer, &amp;class::method)</code>   </td><td class="markdownTableBodyLeft">Invoke the method on the object with the arguments passed to the mock function.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>InvokeWithoutArgs(f)</code>   </td><td class="markdownTableBodyLeft">Invoke <code>f</code>, which can be a global/static function or a functor. <code>f</code> must take no arguments.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>InvokeWithoutArgs(object_pointer, &amp;class::method)</code>   </td><td class="markdownTableBodyLeft">Invoke the method on the object, which takes no arguments.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>InvokeArgument&lt;N&gt;(arg1, arg2, ..., argk)</code>   </td><td class="markdownTableBodyLeft">Invoke the mock function's <code>N</code>-th (0-based) argument, which must be a function or a functor, with the <code>k</code> arguments.   </td></tr>
</table>
<p>The return value of the invoked function is used as the return value of the action.</p>
<p>When defining a callable to be used with <code>Invoke*()</code>, you can declare any unused parameters as <code>Unused</code>:</p>
<div class="fragment"><div class="line"><a class="code" href="namespacetesting.html#af5cacf4475557b5a3e37af3836564235">using ::testing::Invoke</a>;</div>
<div class="line"><span class="keywordtype">double</span> Distance(<a class="code" href="namespacetesting.html#a603e329ec0263ebfcf16f712810bd511">Unused</a>, <span class="keywordtype">double</span> x, <span class="keywordtype">double</span> y) { <span class="keywordflow">return</span> sqrt(x*x + y*y); }</div>
<div class="line">...</div>
<div class="line">EXPECT_CALL(mock, Foo(<span class="stringliteral">&quot;Hi&quot;</span>, _, _)).WillOnce(<a class="code" href="namespacetesting.html#af5cacf4475557b5a3e37af3836564235">Invoke</a>(Distance));</div>
<div class="ttc" id="anamespacetesting_html_a603e329ec0263ebfcf16f712810bd511"><div class="ttname"><a href="namespacetesting.html#a603e329ec0263ebfcf16f712810bd511">testing::Unused</a></div><div class="ttdeci">internal::IgnoredValue Unused</div><div class="ttdef"><b>Definition:</b> cmake-build-debug/googletest-src/googlemock/include/gmock/gmock-actions.h:1198</div></div>
<div class="ttc" id="anamespacetesting_html_af5cacf4475557b5a3e37af3836564235"><div class="ttname"><a href="namespacetesting.html#af5cacf4475557b5a3e37af3836564235">testing::Invoke</a></div><div class="ttdeci">std::decay&lt; FunctionImpl &gt;::type Invoke(FunctionImpl &amp;&amp;function_impl)</div><div class="ttdef"><b>Definition:</b> cmake-build-debug/googletest-src/googlemock/include/gmock/gmock-actions.h:1345</div></div>
</div><!-- fragment --><p><code>Invoke(callback)</code> and <code>InvokeWithoutArgs(callback)</code> take ownership of <code>callback</code>, which must be permanent. The type of <code>callback</code> must be a base callback type instead of a derived one, e.g.</p>
<div class="fragment"><div class="line">BlockingClosure* done = <span class="keyword">new</span> BlockingClosure;</div>
<div class="line">... <a class="code" href="namespacetesting.html#af5cacf4475557b5a3e37af3836564235">Invoke</a>(done) ...;  <span class="comment">// This won&#39;t compile!</span></div>
<div class="line"> </div>
<div class="line">Closure* done2 = <span class="keyword">new</span> BlockingClosure;</div>
<div class="line">... <a class="code" href="namespacetesting.html#af5cacf4475557b5a3e37af3836564235">Invoke</a>(done2) ...;  <span class="comment">// This works.</span></div>
</div><!-- fragment --><p>In <code>InvokeArgument&lt;N&gt;(...)</code>, if an argument needs to be passed by reference, wrap it inside <code>std::ref()</code>. For example,</p>
<div class="fragment"><div class="line"><a class="code" href="namespacetesting_1_1internal.html#a4c6f0469015303fe29a4f08ba036e6d6">using ::testing::InvokeArgument</a>;</div>
<div class="line">...</div>
<div class="line">InvokeArgument&lt;2&gt;(5, string(<span class="stringliteral">&quot;Hi&quot;</span>), std::ref(foo))</div>
<div class="ttc" id="anamespacetesting_1_1internal_html_a4c6f0469015303fe29a4f08ba036e6d6"><div class="ttname"><a href="namespacetesting_1_1internal.html#a4c6f0469015303fe29a4f08ba036e6d6">testing::internal::InvokeArgument</a></div><div class="ttdeci">auto InvokeArgument(F f, Args... args) -&gt; decltype(f(args...))</div><div class="ttdef"><b>Definition:</b> cmake-build-debug/googletest-src/googlemock/include/gmock/gmock-more-actions.h:509</div></div>
</div><!-- fragment --><p>calls the mock function's #2 argument, passing to it <code>5</code> and <code>string("Hi")</code> by value, and <code>foo</code> by reference.</p>
<h2><a class="anchor" id="autotoc_md126"></a>
Default Action</h2>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft">Matcher   </th><th class="markdownTableHeadLeft">Description    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code><a class="el" href="namespacetesting.html#ae041df61ff61ccb9753ba15b4309e1a6">DoDefault()</a></code>   </td><td class="markdownTableBodyLeft">Do the default action (specified by <code><a class="el" href="cmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-spec-builders_8h.html#a5b12ae6cf84f0a544ca811b380c37334">ON_CALL()</a></code> or the built-in one).   </td></tr>
</table>
<p>{: .callout .note} <b>Note:</b> due to technical reasons, <code><a class="el" href="namespacetesting.html#ae041df61ff61ccb9753ba15b4309e1a6">DoDefault()</a></code> cannot be used inside a composite action - trying to do so will result in a run-time error.</p>
<h2><a class="anchor" id="autotoc_md127"></a>
Composite Actions</h2>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft"></th><th class="markdownTableHeadLeft"></th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>DoAll(a1, a2, ..., an)</code>   </td><td class="markdownTableBodyLeft">Do all actions <code>a1</code> to <code>an</code> and return the result of <code>an</code> in each invocation. The first <code>n - 1</code> sub-actions must return void and will receive a readonly view of the arguments.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>IgnoreResult(a)</code>   </td><td class="markdownTableBodyLeft">Perform action <code>a</code> and ignore its result. <code>a</code> must not return void.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>WithArg&lt;N&gt;(a)</code>   </td><td class="markdownTableBodyLeft">Pass the <code>N</code>-th (0-based) argument of the mock function to action <code>a</code> and perform it.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>WithArgs&lt;N1, N2, ..., Nk&gt;(a)</code>   </td><td class="markdownTableBodyLeft">Pass the selected (0-based) arguments of the mock function to action <code>a</code> and perform it.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>WithoutArgs(a)</code>   </td><td class="markdownTableBodyLeft">Perform action <code>a</code> without any arguments.   </td></tr>
</table>
<h2><a class="anchor" id="autotoc_md128"></a>
Defining Actions</h2>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft"></th><th class="markdownTableHeadLeft"></th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code><a class="el" href="cmake-build-release_2googletest-src_2googlemock_2include_2gmock_2gmock-actions_8h.html#a7af7137aa4871df4235881af377205fe">ACTION(Sum)</a> { return arg0 + arg1; }</code>   </td><td class="markdownTableBodyLeft">Defines an action <code>Sum()</code> to return the sum of the mock function's argument #0 and #1.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code><a class="el" href="cmake-build-release_2googletest-src_2googlemock_2include_2gmock_2gmock-actions_8h.html#af5f47e069acb517db9f743f029471aa7">ACTION_P(Plus, n)</a> { return arg0 + n; }</code>   </td><td class="markdownTableBodyLeft">Defines an action <code>Plus(n)</code> to return the sum of the mock function's argument #0 and <code>n</code>.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>ACTION_Pk(Foo, p1, ..., pk) { statements; }</code>   </td><td class="markdownTableBodyLeft">Defines a parameterized action <code>Foo(p1, ..., pk)</code> to execute the given <code>statements</code>.   </td></tr>
</table>
<p>The <code>ACTION*</code> macros cannot be used inside a function or class.</p>
<h1><a class="anchor" id="CardinalityList"></a>
Cardinalities</h1>
<p>These are used in <code>Times()</code> to specify how many times a mock function will be called:</p>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft"></th><th class="markdownTableHeadLeft"></th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>AnyNumber()</code>   </td><td class="markdownTableBodyLeft">The function can be called any number of times.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>AtLeast(n)</code>   </td><td class="markdownTableBodyLeft">The call is expected at least <code>n</code> times.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>AtMost(n)</code>   </td><td class="markdownTableBodyLeft">The call is expected at most <code>n</code> times.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>Between(m, n)</code>   </td><td class="markdownTableBodyLeft">The call is expected between <code>m</code> and <code>n</code> (inclusive) times.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>Exactly(n) or n</code>   </td><td class="markdownTableBodyLeft">The call is expected exactly <code>n</code> times. In particular, the call should never happen when <code>n</code> is 0.   </td></tr>
</table>
<h1><a class="anchor" id="autotoc_md129"></a>
Expectation Order</h1>
<p>By default, the expectations can be matched in <em>any</em> order. If some or all expectations must be matched in a given order, there are two ways to specify it. They can be used either independently or together.</p>
<h2><a class="anchor" id="AfterClause"></a>
The After Clause</h2>
<div class="fragment"><div class="line">using ::testing::Expectation;</div>
<div class="line">...</div>
<div class="line">Expectation init_x = <a class="code" href="cmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-spec-builders_8h.html#a535a6156de72c1a2e25a127e38ee5232">EXPECT_CALL</a>(foo, InitX());</div>
<div class="line">Expectation init_y = <a class="code" href="cmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-spec-builders_8h.html#a535a6156de72c1a2e25a127e38ee5232">EXPECT_CALL</a>(foo, InitY());</div>
<div class="line"><a class="code" href="cmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-spec-builders_8h.html#a535a6156de72c1a2e25a127e38ee5232">EXPECT_CALL</a>(foo, Bar())</div>
<div class="line">     .After(init_x, init_y);</div>
</div><!-- fragment --><p>says that <code>Bar()</code> can be called only after both <code>InitX()</code> and <code>InitY()</code> have been called.</p>
<p>If you don't know how many pre-requisites an expectation has when you write it, you can use an <code>ExpectationSet</code> to collect them:</p>
<div class="fragment"><div class="line">using ::testing::ExpectationSet;</div>
<div class="line">...</div>
<div class="line">ExpectationSet all_inits;</div>
<div class="line"><span class="keywordflow">for</span> (<span class="keywordtype">int</span> i = 0; i &lt; element_count; i++) {</div>
<div class="line">  all_inits += <a class="code" href="cmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-spec-builders_8h.html#a535a6156de72c1a2e25a127e38ee5232">EXPECT_CALL</a>(foo, InitElement(i));</div>
<div class="line">}</div>
<div class="line"><a class="code" href="cmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-spec-builders_8h.html#a535a6156de72c1a2e25a127e38ee5232">EXPECT_CALL</a>(foo, Bar())</div>
<div class="line">     .After(all_inits);</div>
</div><!-- fragment --><p>says that <code>Bar()</code> can be called only after all elements have been initialized (but we don't care about which elements get initialized before the others).</p>
<p>Modifying an <code>ExpectationSet</code> after using it in an <code>.After()</code> doesn't affect the meaning of the <code>.After()</code>.</p>
<h2><a class="anchor" id="UsingSequences"></a>
Sequences</h2>
<p>When you have a long chain of sequential expectations, it's easier to specify the order using <b>sequences</b>, which don't require you to given each expectation in the chain a different name. <em>All expected calls</em> in the same sequence must occur in the order they are specified.</p>
<div class="fragment"><div class="line"><a class="code" href="namespacetesting.html#adae3994eb444d1ad2dd602454b854663">using ::testing::Return</a>;</div>
<div class="line">using ::testing::Sequence;</div>
<div class="line">Sequence s1, s2;</div>
<div class="line">...</div>
<div class="line">EXPECT_CALL(foo, Reset())</div>
<div class="line">    .InSequence(s1, s2)</div>
<div class="line">    .WillOnce(<a class="code" href="namespacetesting.html#adae3994eb444d1ad2dd602454b854663">Return</a>(<span class="keyword">true</span>));</div>
<div class="line"><a class="code" href="cmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-spec-builders_8h.html#a535a6156de72c1a2e25a127e38ee5232">EXPECT_CALL</a>(foo, GetSize())</div>
<div class="line">    .InSequence(s1)</div>
<div class="line">    .WillOnce(<a class="code" href="namespacetesting.html#adae3994eb444d1ad2dd602454b854663">Return</a>(1));</div>
<div class="line"><a class="code" href="cmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-spec-builders_8h.html#a535a6156de72c1a2e25a127e38ee5232">EXPECT_CALL</a>(foo, Describe(A&lt;const char*&gt;()))</div>
<div class="line">    .InSequence(s2)</div>
<div class="line">    .WillOnce(<a class="code" href="namespacetesting.html#adae3994eb444d1ad2dd602454b854663">Return</a>(<span class="stringliteral">&quot;dummy&quot;</span>));</div>
</div><!-- fragment --><p>says that <code>Reset()</code> must be called before <em>both</em> <code>GetSize()</code> <em>and</em> <code>Describe()</code>, and the latter two can occur in any order.</p>
<p>To put many expectations in a sequence conveniently:</p>
<div class="fragment"><div class="line">using ::testing::InSequence;</div>
<div class="line">{</div>
<div class="line">  InSequence seq;</div>
<div class="line"> </div>
<div class="line">  <a class="code" href="cmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-spec-builders_8h.html#a535a6156de72c1a2e25a127e38ee5232">EXPECT_CALL</a>(...)...;</div>
<div class="line">  <a class="code" href="cmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-spec-builders_8h.html#a535a6156de72c1a2e25a127e38ee5232">EXPECT_CALL</a>(...)...;</div>
<div class="line">  ...</div>
<div class="line">  <a class="code" href="cmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-spec-builders_8h.html#a535a6156de72c1a2e25a127e38ee5232">EXPECT_CALL</a>(...)...;</div>
<div class="line">}</div>
</div><!-- fragment --><p>says that all expected calls in the scope of <code>seq</code> must occur in strict order. The name <code>seq</code> is irrelevant.</p>
<h1><a class="anchor" id="autotoc_md130"></a>
Verifying and Resetting a Mock</h1>
<p>gMock will verify the expectations on a mock object when it is destructed, or you can do it earlier:</p>
<div class="fragment"><div class="line">using ::testing::Mock;</div>
<div class="line">...</div>
<div class="line"><span class="comment">// Verifies and removes the expectations on mock_obj;</span></div>
<div class="line"><span class="comment">// returns true if and only if successful.</span></div>
<div class="line">Mock::VerifyAndClearExpectations(&amp;mock_obj);</div>
<div class="line">...</div>
<div class="line"><span class="comment">// Verifies and removes the expectations on mock_obj;</span></div>
<div class="line"><span class="comment">// also removes the default actions set by ON_CALL();</span></div>
<div class="line"><span class="comment">// returns true if and only if successful.</span></div>
<div class="line">Mock::VerifyAndClear(&amp;mock_obj);</div>
</div><!-- fragment --><p>You can also tell gMock that a mock object can be leaked and doesn't need to be verified:</p>
<div class="fragment"><div class="line">Mock::AllowLeak(&amp;mock_obj);</div>
</div><!-- fragment --><h1><a class="anchor" id="autotoc_md131"></a>
Mock Classes</h1>
<p>gMock defines a convenient mock class template</p>
<div class="fragment"><div class="line"><span class="keyword">class </span>MockFunction&lt;R(A1, ..., An)&gt; {</div>
<div class="line"> <span class="keyword">public</span>:</div>
<div class="line">  <a class="code" href="cmake-build-debug_2googletest-src_2googlemock_2include_2gmock_2gmock-function-mocker_8h.html#a05ffc29d0784b131ee178da190d31397">MOCK_METHOD</a>(R, Call, (A1, ..., An));</div>
<div class="line">};</div>
</div><!-- fragment --><p>See this <a href="gmock_cook_book.md#using-check-points">recipe</a> for one application of it.</p>
<h1><a class="anchor" id="autotoc_md132"></a>
Flags</h1>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadLeft">Flag   </th><th class="markdownTableHeadLeft">Description    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyLeft"><code>--gmock_catch_leaked_mocks=0</code>   </td><td class="markdownTableBodyLeft">Don't report leaked mock objects as failures.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyLeft"><code>--gmock_verbose=LEVEL</code>   </td><td class="markdownTableBodyLeft">Sets the default verbosity level (<code>info</code>, <code>warning</code>, or <code>error</code>) of Google <a class="el" href="class_mock.html">Mock</a> messages.   </td></tr>
</table>
</div></div><!-- contents -->
</div><!-- PageDoc -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.2
</small></address>
</body>
</html>
